home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Disktools / GCat 461 / Gcat.doc < prev    next >
Text File  |  1996-09-26  |  18KB  |  400 lines
  1. Gcat:- a simple Amiga disk catalogger by John Marchant (aka "Gnome")
  2. ------
  3.               Version 46.01   29 Oct. 95
  4.  
  5.   This program was developed as a project while learning C.  To anyone
  6. who dislikes my American (?) spelling of "catalog", I say "Tough.  I'm
  7. logging the disks and I like to call the result a catalog."
  8.  
  9. ***********************************************************************
  10.                      ##### NOTICE #####
  11.        PLEASE NOTE that Gcat has not been idiot-proofed.
  12.   There is no protection against making silly data entries in the
  13.   Edit and Insert options.
  14. ***********************************************************************
  15.  
  16.   The program is Public Domain and must be accepted "as is".  NO WARRANTY
  17. is given that it is bug-free, and NO LIABILITY is accepted for any damage
  18. it may do to your hardware, your software or your peace of mind.  However I
  19. use it and I'm happy with it so far as it goes.  I'd call it "cheap and
  20. cheerful".
  21.  
  22.          --------------------------------------------------
  23.  
  24. The following files should be supplied with any copy of this program:-
  25.  
  26. GCat          The catalog program.
  27. CatHelp.txt   The online help text. Should be in the same directory as Gcat.
  28. req.library   Copy this into your libs: directory if you don't have it.
  29. testfile.cat  It's just a sample catalog to play with.
  30. Gcat.doc      The file you are reading. This file includes CatHelp.txt
  31. Gcat.guide    My first attempt at writing an Amigaguide
  32. ppmore        Utility for displaying help text. This should be in your
  33.                  c: or your sys:utilities directory.
  34.  
  35.          ---------------------------------------------------
  36.  
  37. Gcat may be started from the CLI or from Workbench.
  38.  
  39. If started from CLI with an argument c (i.e.  "Gcat c") an
  40. alternative color palette (grey, black, white, yellow) will be used.
  41. Otherwise the Workbench preference setting will be used.
  42.  
  43. If you start it by a CLI command, you should first change directory to the
  44. one in which your Gcat program and this help text are held. Otherwise the
  45. program will not be able to find the help text file, and will complain.
  46. So you should....
  47.  
  48.                cd <path to Gcat drawer>
  49.                run Gcat
  50.  
  51.   or of course you can use a wee startup script that does this for you,
  52. and you could execute this script using an alias.  Or you could be clever
  53. and use IconX to execute the script.
  54.  
  55. If you start from the Workbench icon, there's no need to change directory.
  56.  
  57. There is a limit of 20,000 set on how many files may be added to one
  58. Catalog.  If this limit is reached, Gcat will stop adding files and will
  59. tell you to save your catalog & close down.  (See also "Bugs" below.)
  60.  
  61.  ==== The following text is also in 'CatHelp.txt' for online viewing ====
  62.  
  63. The program is controlled by pulldown menus or hotkeys.
  64.  
  65. USING GCAT
  66. ============
  67.   To add data to your catalog you must first select the drive which will
  68.     be used for collecting data.
  69.   Then you simply insert disks into this drive and press RtAmiga/A each
  70.     time. The rest is automatic.
  71.   If you want to edit or delete an entry, point to it and click with the
  72.     left mouse button. The Edit window appears. Click on Edit or Delete, 
  73.     make any changes, and then click on Accept or Cancel.
  74.   You can also click & drag the pointer to select several lines, but the
  75.     dragging can't be used to de-select items already highlit. To do this
  76.     you must click on individual lines. The reason for this is to avoid
  77.     accidental deselection. (That's my excuse anyway.)
  78.   To insert an extra (new) entry, select the Insert menu option and follow
  79.     the instructions below.
  80.  
  81. The MENUS.
  82. ~~~~~~~~~~~
  83. Options menu
  84. =============
  85. SELECT INPUT DRIVE
  86.   This is the drive from which data will be read & added to the catalog.
  87.   e.g. If you select DF1: then all file names on DF1: will be added to
  88.     the catalog - ** even if they already exist in the catalog **
  89.   Only currently available drives will be offered.
  90.  
  91.   The drive you select here remains the drive used for gathering more data,
  92.     unless you select a new one from this menu option. It is unaffected by
  93.     the drive & file you may select to "Load Existing Cat" (though these
  94.     may be the same file & drive).
  95.  
  96. ADD DATA FROM DISK (RtAm/A)
  97.   This will cause the 'Input Drive' to be scanned, and all file names
  98.     (except those with .info extensions) will be appended to the current
  99.     catalog file in memory.
  100.  
  101.   The Catalog file will then be sorted & displayed without further menu
  102.     selection, and you can use the editing facilities described below under
  103.     'Load Existing Catalog'.
  104.  
  105.   You may then proceed to select further menu options, such as add
  106.     further data (from the selected "Input Drive"), change the current
  107.     input drive, or load an existing catalog.
  108.  
  109.   If you see "FILES LIMIT EXCEEDED. SAVE CATALOG & QUIT", you should Quit
  110.     at the earliest opportunity. Saving is not compulsory, but do NOT try
  111.     to add any more files to the catalog.
  112.  
  113. SAVE FILE  (RtAm/S)
  114.     When you load an existing catalog file, or "add data from disk",
  115.   file names forming the catalog are read into memory. If any change is
  116.   made (edits, additions, deletions) you may wish to save the altered
  117.   catalog. If you ask to load a new catalog or quit without having
  118.   saved, a requester will remind you and ask if you wish to save.
  119.     If a catalog file name has not yet been specified, a requester
  120.   will appear for this purpose.
  121.  
  122. SAVE AS    (RtAm/N)
  123.     This is the same as SAVE FILE but asks you the name of the file you
  124.   wish to save to. e.g. you may wish to save it in a different place or
  125.   under a different name. (The 'N' hotkey represents "Name").
  126.  
  127. LOAD A CAT FILE    (RtAm/L)
  128.   This enables you to read an existing catalog. A requester will appear
  129.     for you to select the path and file.
  130.  
  131.   The file & drive you select here do not alter the current input drive.
  132.     If you want to add data to the catalog you select here and it's on
  133.     a different drive, you must use "Select Drive" to set the new
  134.     "current input drive".
  135.  
  136. START NEW CAT
  137.   Use this to clear the current catalog held in memory and begin a new
  138.     one. If changes have been made to a catalog currently held, you'll
  139.     be asked if you wish to save this first.
  140.  
  141. SELECT SORT
  142.   This produces a submenu with 2 options:
  143.     SORT ON FILENAME  (RtAm/1)
  144.     SORT ON DISKNAME  (RtAm/2)
  145.   These control the presentation of the list on screen. You can change
  146.     the sort at any time.
  147.  
  148. QUIT  (RtAm/Q)
  149.   This is a way to exit the program. You can also exit by using the window
  150.     close gadget. If a catalog is currently in memory & has not been saved
  151.     since it was last changed, a requester will appear to remind you.
  152.  
  153.             ------------------------------------------------
  154.  
  155. Insert Menu
  156. =============
  157.   INSERT ITEM  (RtAm/I)
  158.   ------------
  159.   Selecting this will bring up an 'Insert window' with several string
  160.     gadgets, and 2 button gadgets (OK and Cancel).
  161.  
  162.   There are 4 fields to be entered:
  163.        File Name    Path     File size (bytes)    Date
  164.   
  165.   See also "Edit window" below.
  166.  
  167.   Until the program is properly idiot-proofed, care should be taken to
  168.     enter data correctly. See the screen display for formats.
  169.   After making an entry and clicking on Accept, the new item is planted
  170.     in the file list, which is then re-sorted and displayed.
  171.  
  172.  
  173. Help Menu
  174. ==========
  175.   HELP  (RtAm/H or Help key)
  176.   -----
  177.   This will move the working screen to back and call ppmore to display
  178.   this text file you are reading. After use, the work screen returns.
  179.  
  180.   Please note that ppmore should be in your C directory, or some other dir
  181.     for which a path has been assigned for commands (e.g. Utilities).
  182.  
  183.  
  184. Printer Menu
  185. =============
  186.   PRINT CATALOG  (RtAm/P)
  187.   --------------
  188.   This formats and prints the catalog file currently displayed.
  189.     You should have your printer ready for action, as printing starts as
  190.     soon as you have made the request.
  191.  
  192.   WRITE TO FILE  (RtAm/W)
  193.   --------------
  194.   This will bring up a requester asking for the path & name of the output
  195.     file. The catalog currently being displayed will be formatted and written
  196.     to the selected output file. The Catalog data file is packed, with
  197.     many spaces removed, but 'Write to file' will format it as it appears
  198.     on the screen.  Unlike 'Print', there will be no page-breaks.
  199.  
  200.   SET PAGE LENGTH
  201.   ----------------
  202.   This allows you to change your print page length from the default 66 
  203.     lines to some other value (eg for A4 cut sheets). Two blank lines will
  204.     always be left at the foot of each page - ie 64 lines will be printed
  205.     on a 66 line page. Note that you cannot change the pagelength during the
  206.     printing.
  207.  
  208.   SET LETTER QUALITY
  209.   -------------------
  210.   Use this option if you want non 'draft' quality and your printer does
  211.     not have a high quality option switch on it. Setting this option
  212.     only changes the copy of your printer preferences currently held
  213.     in memory (and restores to its original setting after printing). 
  214.     It does NOT alter the setting of your Preferences held on disk.
  215.     If you already had 'Letter quality' set in your Preferences, this
  216.     option will make no difference.
  217.  
  218.     ----------------------------------------------------------------
  219.  
  220.   When a Catalog is displayed, you can scroll the text up and down, using
  221.     the proportional gadget or the arrow gadgets at right of screen. You
  222.     can also highlight lines by clicking on them with the left mouse button.
  223.     Selecting lines in this way causes the Selection buttons to appear.
  224.     
  225. The Selection buttons
  226. ----------------------
  227.   If you click on one or more lines on the screen, those lines are
  228.     highlighted and the selection buttons are revealed. 
  229.     Deletions & edits do not take effect until 'Accept' is selected.
  230.  
  231.   Delete:- if you click on this one, you are asking to delete all lines
  232.     you have selected whether or not they have scrolled off the screen.
  233.  
  234.   Edit:- brings up a 'string requester' containing the most recently 
  235.     marked line, and you can edit the line. Press OK to accept, or 
  236.     press Cancel. If more than one line was previously selected, only
  237.     the most recent one can be edited. Any others are unaffected.
  238.  
  239.   Accept:- accepts any changes into the catalog data.
  240.  
  241.   Cancel:- cancels the changes you have made and conceals the selection
  242.     buttons.
  243.  
  244.     ================== End of 'CatHelp.txt' =======================
  245.  
  246. The Catalog file (This section for enthusiasts only!)
  247. -----------------
  248.   This is a text file which may be edited if you wish.  A text editor can be
  249.     used: but be sure to retain the format, which has field separators as 
  250.     described below. (ie the lines are 'packed'.)
  251.  
  252.   Field 1 holds the file names in alphabetical order.
  253.  
  254.   Field 2 holds the disk name from which each file was extracted, and
  255.     the name of the lowest level of sub-directory in which it resides.
  256.     e.g. a file on df0:games/zaptype/Amoeba shows as
  257.                            Amoeba  df0:zaptype
  258.           This is only for reason of space in the line.
  259.  
  260.   Field 3 holds the file size in bytes, left-padded with spaces to 8 characters.
  261.  
  262.   Field 4 holds the date found on the file. If this is silly, then the
  263.     file has a silly date (or you entered it wrongly when editing).
  264.  
  265.   Fields are separated on the file by the vertical bar character |
  266.  
  267.   Until a "search" facility is added, the easiest way to search for a
  268.     file name is by using a text editor such as Cygnus Ed, or the DOS
  269.     "search" facility.
  270.  
  271.    ----------------------------------------------------------------
  272.  
  273. Recent History
  274. ================
  275. Vn 41 Revn 5: Option to use Workbench colours (by default), or my
  276.               own choice of colours (using 'c' argument).
  277.  
  278. Vn 42 Revn 0: The window and all gadgets now size themselves according
  279.               to the user's screen size. This cures problems with
  280.               overscan or non-standard screen heights.
  281.       Revn 1: Printing bug now corrected. Output text looped on
  282.               start of each page from page 3 onwards due to really
  283.               stupid coding error.
  284.       Revn 2: Inability to "see" drive Df2: now fixed.
  285.       Revn 3: Cosmetic tweaks of no consequence
  286.       Revn 4: Tiny bug fixed. It was possible to select a line one
  287.                below the bottom of the display window. Messy!
  288.       Revn 5: Menus disabled while in edit or insert mode. It was
  289.                found possible to ask for a sort while lines were
  290.                marked selected. This crashed the program.
  291.       Revn 6: Bug fix. It wasn't possible to select bottom line of scroll.
  292.               Input device submenu extended to include HD0,1,2,3
  293.  
  294. Vn 43 Revn 0: Cosmetic changes to menus, as requested by users.
  295.                 At LAST I've found out how to put only available
  296.                 disk devices into the drive selection sub-menu!
  297.                 It meant an extra program module, but was worth it.
  298.  
  299.       Revn 1: More cosmetic changes requested by pedantic friends :-)
  300.  
  301.       Revn 2: Bug fix: If the saved file path was long, Gcat crashed.
  302.       Revn 3: Cosmetic changes, & tidying of coding used in Revn.2
  303.  
  304. Vn 44 Revn 0: Hopefully the scrolling now behaves correctly and is not
  305.                 upset by different amounts of vertical screen overscan.
  306.       Revn 1: Bug preventing bottom 1 or 2 lines being selected: fixed.
  307.       Revn 2: Further problems fixed with scrolling on different screen
  308.                 sizes. Is this problem finally fixed? Let's hope so.
  309.  
  310. Vn 45 Revn 0: At last I've figured out how to sort by file name within
  311.                 disk name & path. This fulfils a long-time ambition :-)
  312.       Revn 1: Cosmetic improvement - Menus tidied
  313.       Revn 2: Menus disabled during reading disk or printing.
  314.       Revn 3: "End stop" added to make Gcat finish on 5000 files.
  315.  
  316. Vn 46 Revn 0: Maximum files increased to 20,000 for those freaks who
  317.                 want to catalog a CD.
  318.       Revn 1: Gcat now clones your Workbench screen, to get the display
  319.                 height right.
  320.  
  321. It was my intention to change to ASL requesters. The file requester is
  322.   easy, but a two-gadget input requester is very messy since ASL doesn't
  323.   support this and a further IDCMP channel has to be set up. Using
  324.   Req is far simpler, and in my opinion Req does a nicer file requester.
  325.  
  326.          --------------------------------------------------
  327. BUGS?
  328. ------
  329. 1. If you ask to "Write to disk" a very large catalog (e.g. all of dh0:)
  330.   and try to save to a file in ram: you can get a 'guru'. On a reset
  331.   & retry, the problem goes away. This is with plenty of free ram: so
  332.   maybe it's due to memory fragmentation?
  333.  
  334. 2.  Under low memory conditions the program may hang or crash with a
  335.   "MemoryInsane" alert. The program checks that memory is available while
  336.   reading in data, but certain activities such as sorting evidently need
  337.   more memory & you can run out. I've not met this in regular use with large
  338.   catalogs of 3 or 4 thousand files, but a tester has reported it. The problem
  339.   may be caused by memory fragmentation, so maybe a reset before running would
  340.   avoid it.
  341.  
  342. 3. In Vn 43.01 a small bug turned up when I had more than 11 disk type
  343.   devices available for data input. The "source drive" submenu didn't have
  344.   enough slots in it, and the parent menu was corrupted. You can now have
  345.   up to 15 possible input devices before any problem arises.
  346.  
  347. 4. If you try to read in more than 20,000 files, the program will stop reading
  348.   in more files. The list will be sorted by file names, and you will be told
  349.   to "save catalog and quit". Do NOT sort again by disk name, as this will
  350.   cause an Enforcer hit (a read from low memory). I've been unable to pin
  351.   down the cause, but it lies within the "quicksort" function when sorting
  352.   by diskname. It is all right to save the catalog file, but do not then
  353.   continue with further activities.
  354.  
  355.   If you run out of memory Gcat will close down immediately, to avoid
  356.   crashing your system. But you will have lost your catalog.
  357.  
  358.   The program has been tested on 68000, 68030 and 68040 processors, and with
  359.   Codewatcher and Enforcer. The only Enforcer hit was as described in para 4
  360.   above.
  361.  
  362. User Problems
  363. ---------------
  364.   Bugs or nasties may be reported to me:-
  365.     a) Through fidonet: 2:2500/167.15
  366.              or usenet: gnome@martinac.demon.co.uk
  367.     b) By a message on my Bulletin Board "Moonlight" which is open most
  368.          nights 6pm - 8am.  Tel: +44 (0)1234 212752  (logon, fax or netmail).
  369.          1200 to 14400 baud, V32bis. Standard 8N1 protocol.
  370.     c) By snail mail at the address below.
  371.  
  372.   If possible please supply enough detail so that I can repeat what you
  373.     did to reproduce the bug you observed. Screen grabs are useful.
  374.  
  375. Credits
  376. =========
  377. Thanks to....
  378.  
  379.  Jim Perry of "Studio Services" for field-testing this program, and for
  380.     asking for the sort by disk-name. 
  381.  Bil Irving and Anthony Keeley for suggestions, advice & much winding me up.
  382.  Steve Parkinson for helping with programming problems & showing me how to
  383.     do the sort.
  384.  Chris Sumner for reporting some bugs I didn't know about.
  385.  Phillip Lindsay for the coding to list available disk devices - which I
  386.     discovered one day on Usenet.
  387.  Gavin Hamill for suggestions for improvement.
  388.  Mel Potter for testing, and screen-grabs showing the scroll problem.
  389.  Andrew Westwood for reporting problems on certain screen types, and for
  390.     showing me how to clone a public screen.
  391.  Anthony Keeley for testing upgrades and "discovering" bugs which nobody
  392.     else can reproduce. I've sent him the name of a computer repairer.
  393.  Pink Floyd, Queen, and Nescafe Gold Blend for keeping me awake.
  394.  
  395. -----------------------------
  396. Version 46    October 1995
  397.  
  398. John Marchant,  43 Bowhill, Putnoe, Bedford MK41 8EQ,  UK.
  399. Fidonet:  2:2500/167.15      Internet: gnome@mag-net.co.uk
  400.